/*
 * Copyright 2011 Matt Oliveri
 *
 * This file is part of JConfigGen
 *
 * JConfigGen is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * JConfigGen is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with JConfigGen.  If not, see <http://www.gnu.org/licenses/>.
 */

/** {@code Config} class and other AST classes.
 * <p>
 * This package contains the non-optional parts of JConfigGen, namely the {@code Config} class used to actually output code, and the abstract syntax tree (AST) implementation.
 * You can build an AST yourself using the public interface of the classes in this package.
 * The semantics of the AST are pretty straightforward.
 * First of all, keep in mind that the language is implemented by generating Java code, so there will often be a correspondence between AST features and Java language features.
 * JConfigGen is a preprocessor for Java, as opposed to a full-blown compiler that happens to output Java code.
 * What this means in practice is that the Java code generated by JConfigGen is not guaranteed to be correct for all inputs, only for correct inputs.
 * In other words, JConfigGen relies on the underlying Java compiler to catch certain errors in the Config,
 *   and the original AST is only considered a "correct" Config if neither JConfigGen nor the Java compiler reject it.
 * </p>
 * <p>
 * Most classes in this package correspond to a type of expression in the language.
 * These classes are subclasses of {@code Expr}.
 * An instance of such a class corresponds to an instance of the expression type (i.e. an expression).
 * The semantics of each expression type is documented in the Javadoc for the corresponding class.
 * Expression nesting is encoded using {@code List}s of subexpressions.
 * All expressions are ultimately contained by a {@code Config}, which itself is not an expression.
 * The semantics of the {@code Config} as a whole is documented in the Javadoc for {@code Config}.
 * </p>
 * <p>
 * Some expressions can be optionally assigned an id.
 * This id is a Java identifier that will refer to the result of the expression.
 * The scope of an id follows evaluation order, which is specified case-by-case for each expression type.
 * It starts right after the expression finishes evaluating, and extends to the end of the innermost block that contains the expression.
 * Blocks are nested chunks of code corresponding to lexical scopes, as in Java.
 * In Java, curly braces are used to indicate blocks.
 * In this language, certain AST nodes implicitly introduce blocks.
 * The details of exactly which expressions lie inside vs. outside the block are documented in each such node.
 * Technically, {@code Config} itself introduces a block which contains all expressions in the Config.
 * Currently, the only other node which introduces a block is {@code Block}.
 * It is an error to give an expression an id which is the same as an existing id already in scope.
 * </p>
 * <p>
 * Some expressions can be given the type of their result.
 * The rules for when the result type is needed are complicated, so I won't try to explain them other than to say why, in general, result types are sometimes needed:
 * <blockquote>
 *   Sometimes the generated Java code needs the type included in it somewhere in order to be correct.
 *   This is often when we need to generate a temporary variable to hold the result.
 *   Since JConfigGen does not parse inline Java code, look up method definitions, etc., it will not always know the result type of an expression, so you need to tell it.
 * </blockquote>
 * If you do not specify a result type and JConfigGen determines that it was needed, it will throw an {@code InvalidConfigException} to let you know.
 * If you specify a type that is not assignable from (as defined by Java semantics) the actual type of the expression result, the Java compiler will complain.
 * (I think it's a shame that Java requires a type to be specified in these cases, considering that the compiler just calculates the type itself anyway.)
 * </p>
 * <p>There are some conventions used by these classes which you should be aware of:<ul>
 *   <li>
 *     The AST is a tree.
 *     This means no AST node should be immediately contained by more than one AST node,
 *       and there should be no containment cycles.
 *     Behavior is unspecified if these structural constraints are violated.
 *     There are two ways to use the result of an expression without directly containing the expression:<ul>
 *       <li>Assign the expression an id, then use the id to refer to the result.</li>
 *       <li>Put the expression in a {@code Proxy}, then refer to the result with a {@code PxRef}.</li>
 *     </ul>
 *   </li>
 *   <li>
 *     Some constructors take a {@code Config} reference as a parameter.
 *     You must pass a reference to the {@code Config} that will contain the AST node you are constructing.
 *     Behavior is unspecified if you pass anything else.
 *     (I'm planning to change things so you don't need this.)
 *   </li>
 *   <li>
 *     Some constructors take {@code List}s as parameters.
 *     These {@code List}s are not expected to be in their final state when they are passed to a constructor.
 *     However, they are expected to be in their final state by the time any code output methods of {@code Config} are called.
 *     In particular, behavior is unspecified if the {@code List}s change while code is being generated.
 *     The classes in this package do not modify {@code List}s passed in as arguments.
 *   </li>
 *   <li>
 *     Some constructors take a line number.
 *     The number you provide is intended to help identify part of a text file which corresponds to the AST node.
 *     This number is used when throwing an {@code InvalidConfigException}.
 *     It doesn't affect the generated Java code at all, so if you don't feel like providing it, or it doesn't make sense in your case, just say whatever you want.
 *   </li>
 * </ul></p>
 */
package atma.jconfiggen;
